\name{PLOTR}
\alias{PLOTR}

\title{Create Diagnostic Plots for a NONMEM Run}
\description{
  PLOTR is a function to generate diagnostic plots and/or covariate
  evaluation plots following a successful NONMEM run. It is called by
  NONR if diagnostic plots are requested or can be called independently
  following a NONMEM run. Plots use the pdf device. 
}
\usage{
  PLOTR(
	run, 
	ProjectDir=getwd(), 
	dvname = 'DV', 
	logtrans = FALSE, 
	grp = NULL, 
	grpnames = NULL, 
	cont.cov = NULL, 
	cat.cov = NULL, 
	par.list = NULL, 
	eta.list = NULL, 
	missing = -99,
	epilog=NULL,
	file=NULL,
	rundir=filename(ProjectDir,run),
	outdir=ProjectDir,
	...
)
}

\arguments{
  \item{run}{A control stream name, typically integer.}
  \item{ProjectDir}{The directory containing the NONMEM control (*.ctl) streams.}
  \item{dvname}{Name of the dependent
  variable to use as a label for the diagnostic plots. Default: DV.}
  \item{logtrans}{Whether to transform the NONMEM output variables DV,
  PRED, and IPRED. Default: FALSE.}
  \item{grp}{Item in
  NONMEM datafile or output table file that can be used to condition
  plots generated by PLOTR.  Default value is NULL. Example:
  \code{grp=c("SEX")}.  Can be more than one, e.g,. grp=c("SEX","TRT").}
  \item{grpnames}{Optional vector of names for
  \code{grp} item. Vector length must equal number of conditions in
  \code{grp} and must have an order corresponding to an increasing sort
  of \code{grp}.  Default value is NULL. Example:
  \code{grpnames=c("Male","Female")}}
  \item{cont.cov}{Vector of
  continuous covariate names. Names must match those used as column
  headers in \code{DataFile}.  Values are retrieved from \code{DataFile}
  so they do not need to be part of the NONMEM \$TABLE step. Default
  value is NULL.  Example: \code{cont.cov=c("AGE","WT","CLCR")}}
  \item{cat.cov}{Vector of categorical covariate names. Names must match
  those used as column headers in \code{DataFile}.  Values are retrieved
  from \code{DataFile} so they do not need to be part of the NONMEM
  \$TABLE step. Default value is NULL.  Example:
  \code{cat.cov=c("SEX","FOOD")}} 
  \item{par.list}{Vector of NONMEM model
  parameter names.  Values are retrieved from *par.TAB created in
  NONMEM. Default value is NULL.  This can be a superset of parameters
  but only those present in NONMEM output table will be used. Example:
  \code{par.list=c("CL","V","V2","Q")}} 
  \item{eta.list}{Vector of NONMEM
  model random effect names. Values are retrieved from *par.TAB created
  in NONMEM. Default value is NULL This can be a superset of random
  parameters but only those present in NONMEM output table will be used.
  Example: \code{eta.list=c("ETA1","ETA2","ETA3","ETA4")}}
  \item{missing}{Numeric item that defines value used to represent
  missing items in the NONMEM data file. Default value is "-99".}
  \item{epilog}{
  User-defined function or script to call at end of NONR or PLOTR.
  A non-null argument that cannot be coerced by match.fun() to a function
  will be treated as a filename to be sourced.  All the arguments normally
  available to PLOTR (run, ProjectDir, dvname, logtrans, grp, grpnames, cont.cov, 
  at.cov, par.list, eta.list, missing, etc) will be available to epilog, as well
  as any extra arguments you pass to NONR() or PLOTR(). A
  function can declare any of these, but should at minimum contain the 
  \dots argument. A script can expect them to be present.  See also 
  inst/MIfunsExamples/epilog.R in this package.  To see exactly what is available,
  try \code{epilog=function(...)cat(names(list(...)))}.
  }  
  \item{file}{File name for diagnostic plots, if any.  Default combines
  DiagnosticPlotReview with the run number, and \code{grp} if present.  You can specify 
  an alternative name with a counter, additionally supplying \code{onefile=FALSE}.
  Supplying \code{outdir} modifies the default file name.}
  \item{rundir}{Path for the NONMEM run directory (ProjectDir/*).  Passed to dataSynthesis().}
  \item{outdir}{Path for the NONMEM output directory (ProjectDir).  Passed to dataSynthesis().}
  \item{\dots}{Additional arguments passed to functions that accept them. For example,
  you can pass \code{onefile=FALSE} to pdf().  You can also pass
  additional lattice arguments to modify the diagnostic plots. }
}
\details{
  PLOTR creates a plotting dataset using dataSynthesis(). It passes this dataset
  to each of diagnosticPlots(), covariatePlots(), and cwresPlots().  It then 
  calls the function named by the epilog argument, if any.  The example epilog 
  (epilogEx.R) calls dataSynthesis() itself, and does additional plotting.
  
  The \dots argument can be used creatively, with appropriate caution.
  Extra arguments are generally passed to secondary functions that accept them, 
  and even some that don't.  All the lattice plotting functions accept extra 
  arguments, so you may be able to modify the the diagnostic plots judiciously
  (with the caviat that the same arguments will be passed to diagnosticPlots(),
  covariatePlots(), and cwresPlots()). pdf() technically does not accept extra 
  arguments, but any specified argument that it does accept will be passed.  

  File names deserve special consideration.  \code{file} gives
  the name (or naming strategy) for the diagnostic plots; it is passed to pdf().
  \code{tabfile}, \code{ctlfile}, \code{outfile}, \code{datfile}, 
  and \code{parfile} are passed to dataSynthesis().  All have suitable defaults.
  If alternatives are specified, '*' will be replaced with \code{run}, the run number.  
  For example, the default pdf name is ProjectDir/DiagnosticPlotReview\_*.pdf, 
  but you could change it to ProjectDir/*/DiagnosticPlotReview.pdf.
     
}
\value{Used for side effects.}
\references{http://metruminstitute.org; mifuns.googlecode.com}
\author{Tim Bergsma}
\seealso{ 
\itemize{
item \code{\link{NONR}}
item \code{\link{dataSynthesis}}
item \code{\link{diagnosticPlots}}
item \code{\link{covariatePlots}}
item \code{\link{cwresPlots}}
}
}


\keyword{manip}

